package com.quantum.remoting.event
{
	import flash.events.Event;

	/**
	 * This class defines a generic method return event that can used by any class to notify
	 * its caller through a callback. Examples of its use include a proxy calling back at the
	 * completion of a remote method.
	 *
	 * <p>SDK Version 1.0.0</p>
	 */
	[SDK]
	public class OperationReturnEvent extends Event
	{
		private var _result:Object;
		private var _error:Error;

		private var _callContext:Object;
		private var _callee:Object;

		/**
		 * This string is used for the <code>type</code> property if no custom id is provided
		 * to the constructor.
		 */
		public static const OPERATION_RETURN:String="OperationReturn";

		[Result]
		/**
		 * The result or return value from the method invocation whose completion is
		 * represented by this event.
		 */
		public function get result():Object
		{
			return _result;
		}

		[Error]
		/**
		 * The error resulting from the method invocation whose completion is represented
		 * by this event.
		 */
		public function get error():Error
		{
			return _error;
		}

		/**
		 * This property represents an arbitrary call context supplied by the caller to the
		 * callee when invoking the method whose completion is represented by this event.
		 */
		public function get callContext():Object
		{
			return _callContext;
		}

		/**
		 * The callee object is the target of the method invocation whose completion is
		 * represented by this event.
		 */
		public function get callee():Object
		{
			return _callee;
		}

		/**
		 * Initializes a new instance of this class.
		 *
		 * @param result
		 *    Value for the <code>result</code> property.
		 * @param error
		 *    Value for the <code>error</code> property.
		 * @param callContext
		 *    Value for the <code>callContext</code> property.
		 * @param callee
		 *    Value for the <code>callee</code> property.
		 * @param eventId
		 *    Value for the <code>type</code> property.
		 */
		public function OperationReturnEvent(result:Object, //
			error:Error, //												  
			callContext:Object=null, //
			callee:Object=null, //											   
			type:String=OPERATION_RETURN //
			)
		{
			super(type);
			_result=result;
			_error=error;
			_callContext=callContext;
			_callee=callee;
		}

		/**
		 * A convenience factory method for this class that assumes null value for the error.
		 *
		 * @param result
		 *    Value for the <code>result</code> property.
		 * @param callContext
		 *    Value for the <code>callContext</code> property.
		 * @param callee
		 *    Value for the <code>callee</code> property.
		 */
		public static function newOperationReturnEvent(result:Object, callContext:Object=null, callee:Object=null):OperationReturnEvent
		{
			return new OperationReturnEvent(result, null, callContext, callee);
		}

		/**
		 * A convenience factory method for this class that assumes null value for the result.
		 *
		 * @param error
		 *    Value for the <code>error</code> property.
		 * @param callContext
		 *    Value for the <code>callContext</code> property.
		 * @param callee
		 *    Value for the <code>callee</code> property.
		 */
		public static function newErrorEvent(error:Error, callContext:Object=null, callee:Object=null):OperationReturnEvent
		{
			return new OperationReturnEvent(null, error, callContext, callee);
		}

		/**
		 * Creates a clone of this event. All custom events should override this method.
		 *
		 * @return
		 *    A clone of this event.
		 */
		public override function clone():Event
		{
			return new OperationReturnEvent(result, error, callContext, callee, type);
		}
	}
}